Skip to content

Conversation

@tarunb12
Copy link
Contributor

Issue

aws/aws-cdk-rfcs#789

Reason for this change

This change adds a new alpha module for EC2 Image Builder L2 Constructs (@aws-cdk/aws-imagebuilder-alpha), as outlined in aws/aws-cdk-rfcs#789. This PR specifically implements the DistributionConfiguration construct.

Description of changes

This change implements the DistributionConfiguration construct, which is a higher-level construct of CfnDistributionConfiguration.

Example

const distributionConfiguration = new imagebuilder.DistributionConfiguration(this, 'DistributionConfiguration', {
  distributionConfigurationName: 'test-distribution-configuration',
  description: 'A Distribution Configuration',
  amiDistributions: [
    {
      // Distribute AMI to us-east-2 and publish the AMI ID to an SSM parameter
      region: 'us-east-2',
      ssmParameters: [
        {
          parameter: ssm.StringParameter.fromStringParameterAttributes(this, 'CrossRegionParameter', {
            parameterName: '/imagebuilder/ami',
            forceDynamicReference: true
          })
        }
      ]
    }
  ]
});

// For AMI-based image builds - add an AMI distribution in the current region
distributionConfiguration.addAmiDistributions({
  amiName: 'imagebuilder-{{ imagebuilder:buildDate }}',
  amiDescription: 'Build AMI',
  amiKmsKey: kms.Key.fromLookup(this, 'ComponentKey', { aliasName: 'alias/distribution-encryption-key' }),
  // Copy the AMI to different accounts
  amiTargetAccountIds: ['123456789012', '098765432109'],
  // Add launch permissions on the AMI
  amiLaunchPermission: {
    organizationArns: [
      this.formatArn({ region: '', service: 'organizations', resource: 'organization', resourceName: 'o-1234567abc' })
    ],
    organizationalUnitArns: [
      this.formatArn({
        region: '',
        service: 'organizations',
        resource: 'ou',
        resourceName: 'o-1234567abc/ou-a123-b4567890'
      })
    ],
    userGroups: ['all'],
    userIds: ['234567890123']
  },
  // Attach tags to the AMI
  amiTags: {
    Environment: 'production',
    Version: '{{ imagebuilder:buildVersion }}'
  },
  // Optional - publish the distributed AMI ID to an SSM parameter
  ssmParameters: [
    {
      parameter: ssm.StringParameter.fromStringParameterAttributes(this, 'Parameter', {
        parameterName: '/imagebuilder/ami',
        forceDynamicReference: true
      })
    },
    {
      amiAccount: '098765432109',
      dataType: ssm.ParameterDataType.TEXT,
      parameter: ssm.StringParameter.fromStringParameterAttributes(this, 'CrossAccountParameter', {
        parameterName: 'imagebuilder-prod-ami',
        forceDynamicReference: true
      })
    }
  ],
  // Optional - create a new launch template version with the distributed AMI ID
  launchTemplates: [
    {
      launchTemplate: ec2.LaunchTemplate.fromLaunchTemplateAttributes(this, 'LaunchTemplate', {
        launchTemplateName: 'imagebuilder-ami'
      }),
      setDefaultVersion: true
    },
    {
      accountId: '098765432109',
      launchTemplate: ec2.LaunchTemplate.fromLaunchTemplateAttributes(this, 'CrossAccountLaunchTemplate', {
        launchTemplateName: 'imagebuilder-cross-account-ami'
      }),
      setDefaultVersion: true
    }
  ],
  // Optional - enable Fast Launch on an imported launch template
  fastLaunchConfigurations: [
    {
      enabled: true,
      launchTemplate: ec2.LaunchTemplate.fromLaunchTemplateAttributes(this, 'FastLaunchLT', {
        launchTemplateName: 'fast-launch-lt'
      }),
      maxParallelLaunches: 10,
      targetSnapshotCount: 2
    }
  ],
  // Optional - license configurations to apply to the AMI
  licenseConfigurationArns: [
    'arn:aws:license-manager:us-west-2:123456789012:license-configuration:lic-abcdefghijklmnopqrstuvwxyz'
  ]
});

Describe any new or updated permissions being added

N/A - new L2 construct in alpha module

Description of how you validated changes

Validated with unit tests and integration tests. Manually verified generated CFN templates as well.

Checklist


By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

@aws-cdk-automation aws-cdk-automation requested a review from a team November 11, 2025 05:22
@github-actions github-actions bot added p2 beginning-contributor [Pilot] contributed between 0-2 PRs to the CDK labels Nov 11, 2025
@aws-cdk-automation aws-cdk-automation added the pr/needs-further-review PR requires additional review from our team specialists due to the scope or complexity of changes. label Nov 11, 2025
@tarunb12 tarunb12 force-pushed the imagebuilder-distribution branch 3 times, most recently from 1de77fb to cfde029 Compare November 11, 2025 06:41
@tarunb12 tarunb12 marked this pull request as ready for review November 11, 2025 09:30
@kumsmrit kumsmrit self-assigned this Nov 11, 2025
@ozelalisen ozelalisen changed the title feat(imagebuilder): add support for EC2 Image Builder L2 Constructs - Distribution Configuration feat(imagebuilder-alpha): add support for Distribution Configuration Construct Nov 13, 2025
@tarunb12 tarunb12 force-pushed the imagebuilder-distribution branch from cfde029 to 9a9c664 Compare November 13, 2025 21:49
@mergify mergify bot dismissed kumsmrit’s stale review November 13, 2025 21:49

Pull request has been modified.

@tarunb12 tarunb12 force-pushed the imagebuilder-distribution branch from 1fba748 to 5d3ff75 Compare November 13, 2025 21:51
public addAmiDistributions(...amiDistributions: AmiDistribution[]): void {
amiDistributions.forEach((amiDistribution) => {
const region = amiDistribution.region ?? cdk.Stack.of(this).region;
if (!cdk.Token.isUnresolved(region) && this.amiDistributionsByRegion[region]) {
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does this restriction apply to a combination of AmiDistributionConfiguration and ContainerDistributionConfiguration being in same region well?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Correct - each Distribution object must be unique to a region

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The current validations only check for duplicate AMI distributions or duplicate Container distributions in the same region; there is no validation that prevents having both an AMI distribution and a Container distribution for the same region.
With the current implementation, if a user configures both an AMI and a Container distribution for the same region, we will have DistributionProperty for that region that has both amiDistributionConfiguration and containerDistributionConfiguration set. Is that intended?

Distributions: [
{
  region: 'us-east-1',
  amiDistributionConfiguration: { ... },
  containerDistributionConfiguration: { ... },
  ...
}
....
]

@tarunb12 tarunb12 force-pushed the imagebuilder-distribution branch from 722fa15 to bb3a318 Compare November 14, 2025 18:17
@mergify mergify bot dismissed kumsmrit’s stale review November 14, 2025 18:18

Pull request has been modified.

@tarunb12 tarunb12 force-pushed the imagebuilder-distribution branch from bb3a318 to 5f7848e Compare November 14, 2025 18:20
),
);
Object.values(this.containerDistributionsByRegion).forEach((containerDistribution) => {
const region = containerDistribution.region ?? cdk.Stack.of(this).region;
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why not using the map key as region here as well similar to amiDistributionsByRegion, instead of recomputing region?

throw new cdk.ValidationError('You must specify at least one AMI or container distribution', this);
}

const distributionByRegion: { [region: string]: CfnDistributionConfiguration.DistributionProperty } =
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We can simplify this and build the map with explicit loops, to make it more readable:

const distributionByRegion: { [region: string]: CfnDistributionConfiguration.DistributionProperty } = {};

for (const [region, distribution] of Object.entries(this.amiDistributionsByRegion)) {
  distributionByRegion[region] = {
    region,
    amiDistributionConfiguration: this.buildAmiDistribution(distribution),
    fastLaunchConfigurations: this.buildFastLaunchConfigurations(distribution),
    launchTemplateConfigurations: this.buildLaunchTemplateConfigurations(distribution),
    ssmParameterConfigurations: this.buildSsmParameterConfigurations(distribution),
    licenseConfigurationArns: this.buildLicenseConfigurationArns(distribution),
  };
}

for (const [region, containerDistribution] of Object.entries(this.containerDistributionsByRegion)) {
  distributionByRegion[region] = {
    ...(distributionByRegion[region] ?? {}),
    region,
    containerDistributionConfiguration: this.buildContainerDistribution(containerDistribution),
  };
}

stack,
'ContainerDistributionConfiguration',
{
description: 'This is an AMI distribution configuration.',
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
description: 'This is an AMI distribution configuration.',
description: 'This is a Container distribution configuration.',

@gasolima gasolima added the pr/requires-two-approvers This PR is critical (e.g., security, broadly-impacting) and requires 2 approvers to be merged. label Nov 17, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

beginning-contributor [Pilot] contributed between 0-2 PRs to the CDK p2 pr/needs-further-review PR requires additional review from our team specialists due to the scope or complexity of changes. pr/requires-two-approvers This PR is critical (e.g., security, broadly-impacting) and requires 2 approvers to be merged.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants